home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.lzh / wind1.prf < prev    next >
Encoding:
Text File  |  1987-06-23  |  12.8 KB  |  288 lines
  1. .!****************************************************************************
  2. .! 
  3. .! ANTIC PUBLISHING INC., COPYRIGHT 1985.  REPRINTED BY PERMISSION.
  4. .!
  5. .! ** Professional GEM ** by Tim Oren
  6. .!
  7. .! Proff File by ST enthusiasts at
  8. .! Case Western Reserve University
  9. .! Cleveland, Ohio
  10. .! uucp : decvax!cwruecmp!bammi
  11. .! csnet: bammi@case
  12. .! arpa : bammi%case@csnet-relay
  13. .! compuserve: 71515,155
  14. .!
  15. .!****************************************************************************
  16. .!
  17. .!
  18. .!****************************************************************************
  19. .!
  20. .!            Begin Part I
  21. .!
  22. .!****************************************************************************
  23. .!
  24. .PART I Windows
  25. .SH IN THE BEGINNING
  26. In GEM, creating a window and displaying it are two different functions.  The
  27. creation function is called wind_create, and its calling sequence is:
  28. .FB wind_create()
  29. handle = wind_create(parts, xfull, yfull, wfull, hfull);
  30. .FE
  31. This function asks GEM to reserve space in its memory for a new window
  32. description, and to return a code or "handle" which you can use to refer to the
  33. window in the future.  Valid window handles are positive integers; they are not
  34. memory pointers.
  35. .PP
  36. GEM can run out of window handles.  If it does so, the value returned is
  37. negative.  Your code should always check for this  situation and ask the
  38. program's user to close some windows and retry if  possible. Handle zero is
  39. special.  It refers to the "desktop", which is predefined as light green (or
  40. gray) on the ST.  Window zero is always present and may be used, but never
  41. deleted, by the programmer.
  42. .PP
  43. The xfull, yfull, wfull, and hfull parameters are integers which determine
  44. the maximum size of the window.  Xfull and yfull define the upper left corner of
  45. the window, and wfull and hfull specify its width and height. (Note that all of
  46. the window coordinates which we use are in pixel units.)
  47. .PP
  48. GEM saves these values so that the program can get them later when processing
  49. FULL requests.  Usually the best maximum size for a window is the entire
  50. desktop area, excepting the menu bar.  You can find this by asking wind_get  for
  51. the working area of the desktop (handle zero, remember):
  52. .FB wind_get()
  53. wind_get(0, WF_WXYWH, &xfull, &yfull, &wfull, &hfull);
  54. .FE
  55. Note that WF_WXYWH, and all of the other mnemonics used in this article, are
  56. defined in the GEMDEFS.H file in the ST Toolkit.
  57. .PP
  58. The parts parameter of wind_create defines what features will be included in
  59. the window when it is drawn.  It is a word of single bit flags which indicate
  60. the presence/absence of each feature.  To request multiple features, the flags
  61. are "or-ed" together. The flags' mnemonics and meanings are:
  62. .BO
  63. NAME - A one character high title bar at the top of the window.
  64. .EO
  65. .BO
  66. INFO - A second character line below the NAME.
  67. .EO
  68. .BO
  69. MOVER - This lets the user move the window around by "dragging"  in the NAME
  70. area.  NAME also needs to be defined.
  71. .EO
  72. .BO
  73. CLOSER - A square box at the upper left.  Clicking this control point asks
  74. that the window be removed from the screen.
  75. .EO
  76. .BO
  77. FULLER - A diamond at upper right.  Clicking this control point requests
  78. that the window grow to its maximum size, or  shrink back down if it is already
  79. big.
  80. .EO
  81. .BO
  82. SIZER - An arrow at bottom right.  Dragging the SIZER lets  the user choose
  83. a new size for the window.
  84. .EO
  85. .BO
  86. VSLIDE - defines a right-hand scroll box and bar for the window. By dragging
  87. the scroll bar, the user requests that the  window's "viewport" into the
  88. information be moved.   Clicking on the gray box above the bar requests that
  89. the window be moved up one "page". Clicking below the  bar requests a down page
  90. movement.  You have to define  what constitutes a page or line in the
  91. context of your application.
  92. .EO
  93. .BO
  94. UPARROW - An arrow above the right scroll bar.  Clicking here requests that
  95. the window be moved up one "line".  Sliders and arrows almost always appear
  96. together.
  97. .EO
  98. .BO
  99. DNARROW - An arrow below the right scroll bar.  Requests that  window be
  100. moved down a line.
  101. .EO
  102. .BO
  103. HSLIDE - These features are the horizontal equivalent of the RTARROW
  104. above.  They appear at the bottom of the window.  Arrows LFARROW  usually
  105. indicate "character" sized movement left and right. "Page" sized
  106. movement has to be defined by each application.
  107. .EO
  108. .PP
  109. It is important to understand the correspondence between window features and
  110. event messages which are sent to the application by the GEM window manager.  If
  111. a feature is not included in a window's creation,  the user cannot perform the
  112. corresponding action, and your application will  never receive the matching
  113. message type.  For example, a window without a  MOVER may not be dragged by the
  114. user, and your app will never get a WM_MOVED  message for that window.
  115. .PP
  116. Another important principle is that the application itself is responsible for
  117. implementing the user's window action request when a message is received.  This
  118. gives the application a chance to accept, modify, or reject the user's request.
  119. .PP
  120. As an example, if a WM_MOVED message is received, it indicates that the user
  121. has dragged the window.  You might want to byte or word align the requested
  122. position before proceeding to move the window. The wind_set calls used to
  123. perform the actual movements will be described in the next article.
  124. .SH OPEN, SESAME!
  125. The wind_open call is used to actually make the window appear
  126. on the screen.  It animates a "zoom box" on the screen and then draws in the
  127. window's frame.  The calling sequence is:
  128. .FB wind_open()
  129. wind_open(handle, x, y, w, h);
  130. .FE
  131. The handle is the one returned by wind_create.  Parameters x, y, w, and h
  132. define the initial location and size of the window.  Note that these
  133. measurements INCLUDE all of the window frame parts which you have requested. To
  134. find out the size of the area inside the frame, you can use
  135. .FB wind_get()
  136. wind_get(handle, WF_WXYWH, &inner_x, &inner_y, &inner_w, &inner_h);
  137. .FE
  138. Whatever size you choose for the window display, it cannot be any larger than
  139. the full size declared in wind_create.
  140. .PP
  141. Here is a good place to take note of a useful utility for calculating window
  142. sizes.  If you know the "parts list" for a window, and its inner or outer size,
  143. you can find the other size with the wind_calc call:
  144. .FB wind_calc()
  145. wind_calc(parts, kind, input_x, input_y, input_w, input_h, &output_x,
  146. &output_y, &output_w, &output_h);
  147. .FE
  148. Kind is set to zero if the input coordinates are the inner area, and you are
  149. calculating the outer size.  Kind is one if the inputs are the outer size and
  150. you want the equivalent inner size.  Parts are just the same as in wind_create.
  151. .PP
  152. There is one common bug in using wind_open.  If the NAME feature  is
  153. specified, then the window title must be initialized BEFORE opening the window:
  154. .FB wind_set()
  155. wind_set(handle, WF_NAME, ADDR(title), 0, 0);
  156. .FE
  157. If you don't do this, you may get gibberish in the NAME area or the system
  158. may crash.   Likewise, if you have specified the INFO feature, you must make a
  159. wind_set call for WF_INFO before opening the window.
  160. .PP
  161. Note  that ADDR() specifies the 32-bit address of title.  This expression is
  162. portable to other (Intel-based) GEM systems.  If you don't care about
  163. portability, then &title[0], or just title alone will work fine on the ST.
  164. .SH CLEANING UP
  165. When you are done with a window, it should be closed and
  166. deleted.  The call
  167. .FB wind_close()
  168. wind_close(handle);
  169. .FE
  170. takes the window off the screen, redraws the desktop underneath it,
  171. and animates a "zoom down" box.  It doesn't delete the window's
  172. definition, so you can reopen it later.
  173. .PP
  174. Deleting the window removes its definition from the system, and makes that
  175. handle available for reuse.  Always close windows before deleting,  or you may
  176. leave a "dead" picture on the screen.  Also be sure to delete all  of your
  177. windows before ending the program, or your app may "eat" window  handles.  The
  178. syntax for deleting a window is:
  179. .FB wind_delete()
  180. wind_delete(handle);
  181. .FE
  182. .SH THOSE FAT SLIDERS
  183. One of ST GEM's unique features is the proportional
  184. slider bar.  Unlike other windowing systems, this type of bar gives visual
  185. feedback on the fraction of a document which is being viewed, as well as the
  186. position within the document.  The catch, of course, is that you have two
  187. variables to maintain for each scroll bar: size and position.
  188. .PP
  189. Both bar size and position range from 1 to 1000.  A bar size of 1000 fills
  190. the slide box, and a value of one gets the minimum bar size. To compute the
  191. proper size, you can use the formula:
  192. .br
  193. .sp 1
  194. .ce 1
  195. size = min(1000, 1000 * seen_doc / total_doc)
  196. .br
  197. .sp 1
  198. Seen_doc and total_doc are the visible and total size of the document
  199. respectively, in whatever units are appropriate.  As an example, if your window
  200. could show 20 lines of a 100 line text file, you should set a slider size of
  201. 200.  Since the window might be bigger than the total  document at some points,
  202. you need the maximum function.   If the document size is zero, force the slider
  203. size to 1000.  (Note: You will probably  need to do the computation above with
  204. 32-bit arithmetic to avoid overflow  problems).
  205. .PP
  206. Once you have computed the size, use the wind_set function to configure the
  207. scroll bar:
  208. .FB wind_set()
  209. wind_set(handle, WF_VSLSIZE, size, 0, 0, 0);
  210. .FE
  211. This call sets the vertical (right hand) scroll bar.  Use WF_HSLSIZE for the
  212. horizontal scroller.  All of these examples are done for the vertical
  213. dimension, but the principles are identical in the other direction.
  214. .PP
  215. Bar positioning is a little tougher.   The most confusing aspect is that the
  216. 1-1000 range does not set an absolute position of the bar within the
  217. scroll box.  Instead, it positions the TOP of the bar within its
  218. possible range of variation.
  219. .PP
  220. Let's look at our text file example again to make this clearer.  If there are
  221. always 20 lines of a 100 line file visible, then the top of the window must be
  222. always be somewhere between line 1 and line 81. This 80 line range is
  223. the actual freedom of movement of the window. So, if the window were
  224. actually positioned with its top at line 61, it would be at the
  225. three-quarter position within  the range, and we should set a scroll
  226. bar position of 750.  The actual  formula for computing the position is:
  227. .sp 1
  228. .ce 1
  229. pos = 1000 * (top_wind - top_doc) / (total_doc - seen_doc)
  230. .sp 1
  231. Top_wind and top_doc are the top line in the current window and the whole
  232. document, respectively.  Obviously, if seen_doc is greater or equal to
  233. total_doc, you need to force a zero value for pos.  This calculation may seem
  234. rather convoluted the first time through, but is easy once you have done it.
  235. When you have computed the position, wind_set configures the scroll bar:
  236. .FB wind_set()
  237. wind_set(handle, WF_VSLIDE, pos, 0, 0, 0);
  238. .FE
  239. .sp 1
  240. .ce 1
  241. WF_HSLIDE is the equivalent for horizontal scrolling.
  242. .sp 1
  243. It is a good practice to avoid setting the slider size or position if they
  244. are already at the value which you need.  This avoids an annoying redraw flash
  245. on the screen when it is not necessary.  You can check on the current
  246. value of a slider parameter with wind_get:
  247. .FB wind_get()
  248. wind_get(handle, WF_VSLIDE, &curr_value, &foo, &foo, &foo);
  249. .FE
  250. Foo is a dummy variable which needs to be there, but is not used. Substitute
  251. WF_VSLIDE with whatever parameter you are checking.
  252. .PP
  253. One philosophical note on the use of sliders:  It is probably best to avoid
  254. the use of both sliders at once unless it is clearly appropriate to the type of
  255. data which is being viewed.
  256. .PP
  257. Since Write and Paint programs make use of the sheet-of-paper metaphor,
  258. moving the window around in both dimensions is reasonable. However, if the data
  259. is more randomly organized, such as a tableau of icons, then it is probably
  260. better to only scroll in  the vertical dimension and "reshuffle" if
  261. the window's width is changed. Then the user only needs to manipulate
  262. one control to find information which is off-screen.  Anyone who has
  263. had trouble finding a file or folder within a Desktop window will
  264. recognize this problem. 
  265. .SH COMING UP NEXT
  266. In my next column in Antic Online, we'll conclude the tour of the ST's
  267. windowing system.  I'll discuss the correct way to redraw a window's contents,
  268. and how to handle the various messages which an application receives from the
  269. window manager.  Finally, we'll look at a way to redesign the desktop
  270. background to your own specifications.
  271. .SH FEEDBACK
  272. One of the beauties of an on-line column is that you can make your comments
  273. known immediately.  To register your opinions, select ST FEEDBACK, enter your
  274. message, leave your name, and enter a blank line to exit.
  275. .PP
  276. I am interested in hearing proposals for topics, feedback on the technical
  277. level of the column, and reports on bugs and other "features" in both
  278. the column and the ST itself.  Your comments will be read by the ANTIC
  279. staff and myself and, though we might not answer individual questions,
  280. they will be used to steer the course of future columns.
  281. .!
  282. .!
  283. .!*****************************************************************************
  284. .!*                                          *
  285. .!*                End Part 1                      *
  286. .!*                                          *
  287. .!*****************************************************************************
  288.